Node / ReticulumProjects / MeshChatX.git / files / docs / agents / skills / rns-link-api / SKILL.md

Displaying Raw • View rendered • Download

Tc9d1d9# Skill: rns-link-api

Implement or consume the generic RNS Link WebSocket transport and plugin manager capabilities without breaking auth, caching, or disconnect cleanup.

Tc9d1d9## When to use

Tff7b72- Changing Ta5d6ff`rns.link.*` WebSocket handlers or Ta5d6ff`RnsLinkManager`

Tff7b72- Exposing link open/request/send to plugins

Tff7b72- Building external tools that treat MeshChatX as an RNS transport

Tff7b72- Debugging stuck opens, leaked links, or auth failures on link mutators

Tc9d1d9## Protocol (summary)

Client → server types: Ta5d6ff`rns.link.open|identify|request|send|close` with Ta5d6ff`request_id`.

Tff7b72- Ta5d6ff`aspect` is dot-separated RNS app name + sub-aspects (example Ta5d6ff`microrn.mgmt`).

Tff7b72- Payloads are msgpack, base64-encoded (Ta5d6ff`data_b64`, Ta5d6ff`payload_b64`, Ta5d6ff`body_b64`).

Tff7b72- Links are cached per Ta5d6ff`(aspect, destination_hash)`. Ta5d6ff`close` tears down and uncaches.

Tff7b72- In-flight Ta5d6ff`open` / Ta5d6ff`request` tasks cancel when that WebSocket client disconnects.

Tff7b72- Server replies reuse the same Ta5d6ff`type` with Ta5d6ff`status` of Ta5d6ff`phase` / Ta5d6ff`progress` / Ta5d6ff`success` / Ta5d6ff`failure`.

Tff7b72- Broadcasts: Ta5d6ff`rns.link.event` (Ta5d6ff`packet_received`, Ta5d6ff`link_closed`).

Full table: Ta5d6ff`docs/en/rns-link-api.md`.

Tc9d1d9## Auth and plugins

Tff7b72- When password auth is enabled, all Ta5d6ff`rns.link.*` client messages require an authenticated session (same as other WS mutators). See Ta5d6ff`auth-csrf-ws-security`.

Tff7b72- Plugins need Ta5d6ff`permissions.managers` entries such as Ta5d6ff`rnsLink.open` and optional Ta5d6ff`hooks: ["rns.link.event"]`.

Tff7b72- Invoke via Ta5d6ff`POST /api/v1/plugins/{id}/invoke` with Ta5d6ff`method: "callManager"`.

Tff7b72- New manager names must be added to Ta5d6ff`KNOWN_MANAGERS` (see Ta5d6ff`plugin-install-security`).

Tc9d1d9## Key files

Tff7b72- Ta5d6ff`docs/en/rns-link-api.md`

Tff7b72- Ta5d6ff`meshchatx/src/backend/rns_link_manager.py`

Tff7b72- Ta5d6ff`meshchatx/meshchat.py` (WS dispatch, per-client task tracking)

Tff7b72- Ta5d6ff`meshchatx/src/backend/plugin_manager.py`

Tff7b72- Ta5d6ff`meshchatx/src/backend/websocket_config_guard.py`

Tc9d1d9## Verification

Ta5d6ff```Ta5d6ffbash

uv run pytest tests/backend/test_rns_link_manager.py tests/backend/test_rns_link_plugin.py -q --tbTff7b72=short

Ta5d6ff```